Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Common attribute values for visual objects

There are literally hundreds of different attributes, many of which apply only to a single object type. But several basic ones that you will likely use most often apply to most or all visual objects. This section summarizes a few of these.

Geometry attributes

These attributes affect the size and location of the object in the frame or window:

ROW, COLUMN — These DECIMAL attributes are the character positions of the object within its container. For objects in a frame, the values represent the position within the frame and not within the frame’s window. The frame has its own position within its window, and the window has its own position within the display device. When you lay out objects in the AppBuilder, it generates code to position the objects using ROW and COLUMN coordinates. Alternately, you can use pixel values for positions. Generally, character positions are more portable and flexible if the font or display device changes.
X, Y — These INTEGER attributes are equivalent to ROW and COLUMN but measured in pixels.
HEIGHT-CHARS, WIDTH-CHARS — These DECIMAL attributes are the height and width of the object in character units.
HEIGHT-PIXELS, WIDTH-PIXELS — These INTEGER attributes are the height and width of the object in pixels.

Appearance attributes

These attributes affect the appearance of the object:

HIDDEN — If this LOGICAL attribute is true, then the object is hidden and does not appear even when its container is displayed. If it is false, then the object does appear when its container is displayed. If you set the HIDDEN attribute of a container object, such as a window or frame, to true, then the container and all the objects in it are hidden. If you set it to false for a container, then the container and any contained objects that aren’t themselves hidden appear. This is an attribute you can set only at run time. The definition of an object cannot describe it as initially hidden.
VISIBLE — This LOGICAL attribute is not simply the opposite of HIDDEN. Its relation to HIDDEN can be somewhat confusing to understand. Generally, you use it much less than the HIDDEN attribute. Setting the VISIBLE attribute of an object to true forces it to be viewed. For example, setting the VISIBLE attribute of a field-level object in a window to true forces the window to be displayed even if it was previously hidden. By contrast, setting the HIDDEN attribute to false doesn’t force the container to be viewed. You can read all the details of the effects of the VISIBLE attribute in the online help.
SENSITIVE — This LOGICAL attribute determines whether an object is enabled for input or not. Its use is parallel to the ENABLE verb. That is, executing an ENABLE statement for an object is the same as setting its SENSITIVE attribute to true. Similarly, executing a DISABLE statement for an object is the same as setting its SENSITIVE attribute to false. Like the HIDDEN attribute, you can set the SENSITIVE attribute only at run time. This means that if you check the Enable toggle box or the Display toggle box on or off in the AppBuilder property sheet for an object when you are building a screen, you do not change the DEFINE statement the AppBuilder generates for the object. Rather you change the ENABLE and DISPLAY statements the AppBuilder generates that execute when the window is initialized.
READ-ONLY — This LOGICAL attribute applies to data-representation objects and prevents the user from modifying the field value. Sometimes you might want to combine setting the Enable toggle box in a field’s property sheet with setting the READ-ONLY attribute to true. This gives a fill-in field some of the appearance of an enabled field (with its characteristic box outline, which can improve readability), but prevents the user from changing it. The CustOrders window uses this form for its Customer fill-ins.
HELP — This is the help text to display when the object is selected.
TOOLTIP — This is the text to display when the user hovers the mouse over the object. For data-representation objects, you can initialize the ToolTip text in the frame definition for the object, such as in this excerpt from the frame definition for the CustOrders window:

DEFINE FRAME CustQuery      .      .      . Customer.City AT ROW 7.19 COL 13 COLON-ALIGNED VIEW-AS FILL-IN SIZE 27 BY 1 TOOLTIP "Enter the City"      .      .      .

For other types of objects, you can specify the ToolTip text as part of the object definition, as in this button definition:

DEFINE BUTTON BtnFirst LABEL "First" SIZE 15 BY 1.14 TOOLTIP "Press this to see the first Customer.".

LABEL — This CHARACTER attribute is the label of the field or button.
SELECTABLE — You can set up most visual objects for direct manipulation. This means that the user can actually select, move, and resize the object at run time just as you can move and resize objects in a design window in the AppBuilder. The AppBuilder uses these attributes to provide you with the behavior you see in a design window, where you can drag objects around to where you want them. The SELECTABLE attribute is a LOGICAL value which, if true, allows the user to select the object by clicking on it with the mouse. It then sprouts the characteristic resize handles around the object border that let the user size or move it.
RESIZABLE — You can set this LOGICAL attribute to true to let a user change the size of an object at run time. You must also set the SELECTABLE attribute to true to provide the resize handles.
MOVABLE — You can set this LOGICAL attribute to true to let a user move an object at run time. You do not need to set the SELECTABLE attribute to make an object movable. The user can move the object without using its resize handles. However, it is considered a more standard user provision to set SELECTABLE along with MOVABLE.

Data management attributes

These attributes affect how to manage data associated with the object:

SCREEN-VALUE — There is a special screen buffer that holds the displayed values of all data-representation objects in a frame. This buffer is separate from the underlying database record buffer for database fields and from the buffer where variable values are held. If a user enters a value into a field on the screen, that value is not assigned to the underlying record buffer until you execute an ASSIGN statement for the field. In the meantime, the input value is held only in the screen buffer. You can retrieve a value from the screen buffer using the SCREEN-VALUE attribute, which is a CHARACTER value representing the value as it appears on the screen, or as it would appear on the screen in a fill-in field. You can also set the SCREEN-VALUE attribute of an object to display a value without setting the underlying record value. It is important to remember that the value of the SCREEN-VALUE attribute is always the formatted value as it appears in the user interface. If this contains special format mask characters (such as commas and decimal points in a decimal value, for example), then any comparisons you do against this string must include those format characters. If this presents problems, you must assign the screen value to its underlying record buffer and reference the BUFFER-VALUE of the field to access it in its native data type and without format characters.
INITIAL — This attribute holds the initial value of a data-representation object. You can set it only in the DEFINE statement.

Relationship attributes

These attributes affect how the object interacts with other objects:

FRAME-NAME — This CHARACTER attribute holds the name of the container frame the object is in.
FRAME — This HANDLE attribute holds the object handle of the container frame the object is in. In later chapters, you learn how to traverse from one handle to another to locate an object or to locate all objects that are in a container.
WINDOW — This HANDLE attribute holds the object handle of the container window the object is in.

Identifying attributes

These attributes identify characteristics of the object:

NAME — This CHARACTER attribute holds the name of the object.
PRIVATE-DATA — This CHARACTER attribute lets you associate any free-form text with an object, which can help program logic that determinse how to identify or treat the object at run time.

You can see most of the object attributes that you can set for an object type in the AppBuilder property sheet for the object, such as the one shown in Figure 8–1 for the Customer.Name fill-in field in the CustOrders window.

Figure 8–1: Property sheet for a fill-in field

The Advanced button takes you to the dialog box shown in Figure 8–2. These are attributes that you might use less often, some of which are mentioned in this chapter.

Figure 8–2: Advanced Properties dialog box

Certain property sheet settings, such as Display and Enable, affect AppBuilder-generated executable statements and preprocessor values rather than the DEFINE statement for the object itself. You’ve seen the effect of the Display and Enable settings already in the code for the AppBuilder-generated enable_UI procedure:

IF AVAILABLE Customer THEN      DISPLAY Customer.CustNum Customer.Name Customer.Address Customer.City           Customer.State        WITH FRAME CustQuery IN WINDOW CustWin.    ENABLE BtnFirst BtnNext BtnPrev BtnLast Customer.CustNum Customer.Name         Customer.Address Customer.City Customer.State OrderBrowse dTotalPrice         dTotalExt dAvgDisc cWorstWH cBestWH        WITH FRAME CustQuery IN WINDOW CustWin.

The AppBuilder also keeps the list of displayed and enabled objects in preprocessor values:

&Scoped-define FIELDS-IN-QUERY-CustQuery Customer.CustNum Customer.Name ~ Customer.Address Customer.City Customer.State &Scoped-define ENABLED-FIELDS-IN-QUERY-CustQuery Customer.CustNum ~ Customer.Name Customer.Address Customer.City Customer.State

Other property sheet settings for attributes that you cannot set as part of the object definition are set in a series of ASSIGN statements the AppBuilder generates, such as these for the READ-ONLY, PRIVATE-DATA, SELECTABLE, MOVABLE, and RESIZABLE attributes in this example:

ASSIGN      BtnFirst:PRIVATE-DATA IN FRAME CustQuery     =                "Private data for the first button.". ASSIGN      cBestWH:READ-ONLY IN FRAME CustQuery         = TRUE. ASSIGN      cWorstWH:SELECTABLE IN FRAME CustQuery       = TRUE      cWorstWH:MOVABLE IN FRAME CustQuery          = TRUE      cWorstWH:READ-ONLY IN FRAME CustQuery        = TRUE      cWorstWH:RESIZABLE IN FRAME CustQuery        = TRUE.

As you develop your own applications, you need to keep in mind which attributes you can define in a DEFINE statement, which in a frame definition, and which only in executable statements at run time.